---
title: 'CLI Reference'
description: 'Everything to do with the CLI'
---

It all starts with calling
```bash
$ agentstack
```

### Shortcut Aliases
Many top-level AgentStack commands can be invoked using a single-letter prefix to save keystrokes. These are indicated
in the command's documentation here after a `|` character. Run `agentstack help` for the full list. 

### Global Flags
These flags work with all commands:

`--debug` - Print a full traceback when an error is encountered. This also enables printing additional debug information
from within AgentStack useful for development and debugging. 

`--path=<path>` - Set the working directory of the current AgentStack project. By default `agentstack` works inside of the
current directory and looks for an `agentstack.json` file there. By passing a path to this flag you can work on a project
from outside of it's directory.

`--version` - Prints the current version and exits.


## `$ agentstack init`
This initializes a new AgentStack project.
```bash
agentstack init <slug_name>
```

`slug_name` is the name of your project, and will be created as a directory to initialize your project inside. When the
default arguments are passed, a starter project template will be used, which adds a single agent, a single task and
demonstrates the use of a tool. 

### Init Creates a Virtual Environment
AgentStack creates a new directory, initializes a new virtual environment, installs dependencies, and populates the project 
structure. After `init` completes, `cd` into the directory, activate the virtual environment with `source .venv/bin/activate`.
Virtual environments and package management are handled by the `uv` package manager. 

### Initializing with the Wizard
You can pass the `--wizard` flag to `agentstack init` to use an interactive project configuration wizard. 

### Initializing from a Template
You can also pass a `--template=<template_name>` argument to `agentstack init` which will pre-populate your project with functionality
from a built-in template, or one found on the internet. A `template_name` can be one of three identifiers:

- A built-in AgentStack template (see the `templates` directory in the AgentStack repo for bundled templates).
- A template file from the internet; pass the full https URL of the template.
- A local template file; pass an absolute or relative path. 


## `$ agentstack run`
This runs your AgentStack project.
```bash
agentstack run
```

Environment variables will be loaded from `~/.env` and from the `.env` file inside your project directory. Make sure you
have enabled your project's `venv` before executing to include all dependencies required. 

### Overriding Inputs
Your project defines Inputs which are used to customize the Agent and Task prompts for a specific task. In cases where
using the `inputs.yaml` file to populate data is not flexible enough, `run` can accept value overrides for all defined 
inputs. Use `--input-<input_key>=<input_value>` to pass data which will only be used on this run. 

For example, if you have a key in your `inputs.yaml` file named `topic` and want to override it for this run, you would
use the following command:

```bash
agentstack run --input-topic=Sports
```

### Running other project commands
By default, `run` will call the `main()` function inside your project's `main.py` file. You can pass alternate function
names to run with `--function=<function_name>`.


## Generate
Code generation commands for automatically creating new agents or tasks.

### `$ agentstack generate agent | agentstack g a`
Generate a new agent
- `agent_name` (required | str) - the name of the agent
- `--role` (optional | str) - Prompt parameter: The role of the agent
- `--goal` (optional | str) - Prompt parameter: The goal of the agent
- `--backstory` (optional | str) - Prompt parameter: The backstory of the agent
- `--llm` (optional | `<provider>/<model>`) - Which model to use for this agent

#### Default LLM
All arguments to generate a new Agent are optional. A default LLM can be configured in `agentstack.json`under the 
`default_model` setting to populate a provider/model. If you are generating an agent in a project which does not have
a default model set, you will be prompted to configure one. 

#### Example
```bash Generate Agent
agentstack generate agent script_writer
```

### `$ agentstack generate task | agentstack g t`
Generate a new task
- `task_name` (required | str) - the name of the task
- `--description` (optional | str) - Prompt parameter: Explain the task in detail
- `--expected_output` (optional | str) - What is the expected output from the agent (ex: data in json format)
- `--agent` (optional | str) - The name of the agent of which to assign the task to (when using Crew in sequential mode)

#### Example
```bash Generate Task
agentstack g t gen_script --description "Write a short film script about secret agents"
```

## Tools
Tools are what make AgentStack powerful. Adding and removing Tools from Agents is easy with this command. 

### `$ agentstack tools list | agentstack t l`
Lists all tools available in AgentStack.

### `$ agentstack tools add | agentstack t a`
Shows an interactive interface for selecting which Tool to add and which Agents to add it to.

#### Add a Tool to all Agents
When a tool_name is provided it will be made available to all Agents in the project. 
```bash
$ agentstack tools add <tool_name>
```

#### Add a Tool to a single Agent
When an agent_name is provided, the tool will be made available to only that agent. 
```bash
$ agentstack tools add <tool_name> --agent=<agent_name>
```

#### Add a Tool to multiple Agents
When a comma-separated list of Agents is passed, the tool will be made available to those agents. 
```bash
$ agentstack tools add <tool_name> --agents=<agent_name>,<agent_name>,<agent_name>
```

### `$ agentstack tools remove <tool_name>`
Removes a tool from all Agents in the project. 


## Templates
Projects can be exported into a template to facilitate sharing configurations. Re-initialize a project from a template
with `agentstack init --template=<filename>`.

### `$ agentstack export <filename>`
The current project will be written to a JSON template at the provided filename. 

## `$ agentstack update`
Check for updates and allow the user to install the latest release of AgentStack. 

## `$ agentstack login`
Authenticate with [agentstack.sh](https://agentstack.sh) for hosted integrations. 

